# Code Snippets [Including code snippets in Markdown]

Code Snippets in Vocs come in two forms:

- a virtual file snippet in your Markdown code ([Virtual File Snippets](#virtual-file-snippets)), or
- a physical file snippet in your file system ([Physical File Snippets](#physical-file-snippets))

We will show you both approaches below.

## Virtual File Snippets

::::steps

### Create the code snippet

We will create a virtual file snippet called `example.ts`. We can define a virtual file in markdown using the `filename="example.ts"{:ts}` meta tag.

````mdx [example.md]
```ts filename="example.ts" // [!code hl]
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
```
````

### Import the snippet

Next, we will import the snippet into our Markdown file using the `// [!include ...]` marker.

````mdx [example.md]
#### Create your Client

```ts filename="example.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
```

#### Use Actions

```ts // [!code focus]
// [\!include example.ts] // [!code hl] // [!code focus]
 
const blockNumber = await client.getBlockNumber() // [\!code focus] // [!code focus]
``` // [!code focus]
````

### Output

The resulting output will look like this:

<div>
#### Create your Client

```ts filename="example.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
```

#### Use Actions

```ts
// [!include example.ts]
 
const blockNumber = await client.getBlockNumber() // [!code focus]
```
</div>

::::


## Physical File Snippets

::::steps

### Create the code snippet

We will create a physical file snippet called `example.ts`. Let's put this under a `snippets/` directory in your codebase.

```ts [docs/snippets/example.ts]
// [!include ~/snippets/example.ts:import]

// [!include ~/snippets/example.ts:setup]
```

### Import the snippet

Next, we will import the snippet into our Markdown file using the `// [!include ...]` marker.

````mdx [example.md]
#### Create your Client

```ts // [!code focus]
// [\!include ~/snippets/example.ts] // [!code hl] // [!code focus]
``` // [!code focus]

#### Use Actions

```ts // [!code focus]
// [\!include ~/snippets/example.ts] // [!code hl] // [!code focus]
 
const blockNumber = await client.getBlockNumber() // [\!code focus] // [!code focus]
``` // [!code focus]
````

:::info
The `"~"` in the path refers to the [root (`config.rootDir`) directory](/docs/structure#root-directory) of the project.
:::

### Output

The resulting output will look like this:

<div>
#### Create your Client

```ts 
// [!include ~/snippets/example.ts:import]

// [!include ~/snippets/example.ts:setup] 
``` 

#### Use Actions

```ts
// [!include ~/snippets/example.ts:import]

// [!include ~/snippets/example.ts:setup]
 
const blockNumber = await client.getBlockNumber() // [!code focus]
```
</div>

::::

## Regions

You can also include a specific region of a code snippet by using the `// [!region]` and `// [!endregion]` markers.

```ts [docs/snippets/example.ts]
// [\!region import] // [!code focus]
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
// [\!endregion import] // [!code focus]

// [\!region setup] // [!code focus]
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
// [\!endregion setup] // [!code focus]

// [\!region usage] // [!code focus]
const blockNumber = await client.getBlockNumber()
// [\!endregion usage] // [!code focus]
```

Then, we can include the regions in the Markdown with the `// [!include]` marker:

````md [example.md]
```ts
import { writeFileSync } from 'node:fs'
// [\!include ~/snippets/example.ts:import] // [!code focus]

// [\!include ~/snippets/example.ts:setup] // [!code focus]

// [\!include ~/snippets/example.ts:usage] // [!code focus]

writeFileSync('test.txt', blockNumber.toString())
```
````

Which will result in the snippet being rendered like this:

```ts
import { writeFileSync } from 'node:fs'
// [!include ~/snippets/example.ts:import] 

// [!include ~/snippets/example.ts:setup] 

// [!include ~/snippets/example.ts:usage-1] 

writeFileSync('test.txt', blockNumber.toString())
```

### Duplicate variable declarations

When writing snippets, you may run into a scenario where you want to define multiple regions that share the same variable name.

To avoid type errors, you can use the `_$` suffix to discriminate the variable name.

The rendered snippet will still use the original variable name (ie. the name before the `_$` suffix).

```ts
// [!region import]
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
// [!endregion import]

// [!region setup]
const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
// [!endregion setup]

// [!region usage-1] // [!code focus]
const block_$1 = await client.getBlock() // [!code focus]
// [!endregion usage-1] // [!code focus]

// [!region usage-2] // [!code focus]
const block_$2 = await client.getBlock({ blockNumber: 42069n }) // [!code focus]
// [!endregion usage-2] // [!code focus]

// [!region usage-3] // [!code focus]
const block_$3 = await client.getBlock({ blockTag: 'latest' }) // [!code focus]
// [!endregion usage-3] // [!code focus]
```

## Find and Replace

You can use `/(find)/(replace)/` syntax to find and replace text in the snippet.

:::code-group

````md [example.md]
```ts
import { writeFileSync } from 'node:fs'
// [\!include ~/snippets/example.ts /viem/@viem\/core/ /mainnet/sepolia/] // [!code focus]

writeFileSync('test.txt', blockNumber.toString())
```
````

```ts [docs/snippets/example.ts]
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const blockNumber = await client.getBlockNumber()
```

:::

Which will result in the snippet being rendered like this:

```ts 
import { writeFileSync } from 'node:fs'
// [!include ~/snippets/example.ts:import /viem/@viem\/core/ /mainnet/sepolia/]

// [!include ~/snippets/example.ts:setup /mainnet/sepolia/]

// [!include ~/snippets/example.ts:usage-1]

writeFileSync('test.txt', blockNumber.toString())
```

## Tip: Code Block Markers

We can also include markers like [line highlight (`// [!code hl]`)](/docs/markdown#line-highlights) in our code snippets.

:::code-group

```ts [docs/snippets/example.ts]
// [!include ~/snippets/example.ts:import]

// [!include ~/snippets/example.ts:setup]

// [!include ~/snippets/example.ts:usage-2-docs]
```

````md [example.md]
```ts
import { writeFileSync } from 'node:fs'
// [\!include ~/snippets/example.ts]

writeFileSync('test.txt', blockNumber.toString())
```
````

:::

Which will result in the snippet being rendered like this:

```ts 
import { writeFileSync } from 'node:fs'
// [!include ~/snippets/example.ts:import]

// [!include ~/snippets/example.ts:setup]

// [!include ~/snippets/example.ts:usage-2]

writeFileSync('test.txt', blockNumber.toString())
```

## Tip: Twoslash

We can also include Twoslash markers in our code snippets.

:::code-group

```ts [docs/snippets/example.ts]
// [!include ~/snippets/example.ts:import]

// [!include ~/snippets/example.ts:setup]

// [!include ~/snippets/example.ts:usage-4]
```

````md [example.md]
```ts twoslash
// [\!include ~/snippets/example.ts]
```
````

:::

Which will result in the snippet being rendered like this:

```ts twoslash
// [!include ~/snippets/example.ts:import]

// [!include ~/snippets/example.ts:setup]

// [!include ~/snippets/example.ts:usage-4]
```

## Tip: Twoslash + Virtual Files

We can also use virtual files with Twoslash code blocks.

````md [Markdown]
:::code-group

```ts twoslash [example.ts] // [!code hl]
import { client } from './client.js'

const blockNumber = await client.getBlockNumber()
```

```ts twoslash [client.ts] filename="client.ts" // [!code hl]
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
export const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
```

:::
````

Which will result in the snippet being rendered like this:

:::code-group

```ts twoslash [example.ts]
import { client } from './client.js'

const blockNumber = await client.getBlockNumber()
```

```ts twoslash [client.ts] filename="client.ts"
import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
 
export const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
```

:::